<template><div><h2 id="贡献者指引" tabindex="-1"><a class="header-anchor" href="#贡献者指引"><span>贡献者指引</span></a></h2>
<ul>
<li><a href="#2e79fd" title="报告问题">报告问题</a></li>
<li><a href="#db1af3" title="Git 工作流程">Git 工作流程</a></li>
</ul>
<h2 id="报告问题-report-an-issue" tabindex="-1"><a class="header-anchor" href="#报告问题-report-an-issue"><span>报告问题（Report an Issue）</span></a></h2>
<p>在创建一个问题的时候，为了能更迅速地解决问题，请遵循以下原则:</p>
<ul>
<li>提供的信息包括：PHP 和 Yii 的版本，操作系统和 Web 服务器的类型，浏览器的类型和版本；</li>
<li>如果可用，请提供 <strong>完整的</strong> 错误调用堆栈。我们非常欢迎用截图来解释这个问题。</li>
<li>描述问题复现的步骤，当然，如果您能够提供代码来复现这个问题，那就更好了。</li>
<li>如果可能的话，你甚至可以创建一个失败的单元测试，并将其 <a href="#db1af3">作为拉请求（pull request）发送</a>。</li>
</ul>
<p>如果该问题与某个官方扩展相关，请在扩展仓库的问题跟踪器（issue tracker）中报告它。<br>
如果您不确定，可以 <a href="https://github.com/yiisoft/yii2/issues/new" title="向主仓库报告" target="_blank" rel="noopener noreferrer">向主仓库报告</a>（<a href="https://github.com/yiisoft/yii2/issues" target="_blank" rel="noopener noreferrer">github.com/yiisoft/yii2/issues</a>）。</p>
<p><strong>在以下情况下，请不要报告问题：</strong></p>
<ul>
<li>当您正在问如何使用一些 Yii 的特性。此时，您应该使用 <a href="https://forum.yiiframework.com/index.php/forum/42-general-discussions-for-yii-20/" target="_blank" rel="noopener noreferrer">论坛</a> 或 <a href="https://www.yiiframework.com/chat/" target="_blank" rel="noopener noreferrer">聊天室</a> 来达到这个目的。</li>
<li>当您的问题是关于安全的时候，请 <a href="https://www.yiiframework.com/security/" target="_blank" rel="noopener noreferrer">直接联系我们</a> 报告安全问题。</li>
</ul>
<p><strong>避免重复问题</strong></p>
<p>在您报告问题之前，请搜索查遍 <a href="https://github.com/yiisoft/yii2/issues" target="_blank" rel="noopener noreferrer">现有的问题</a>，来看看您的问题是否已经报告或者修复，以确保您没有报告重复的问题。而且，您还要确保您有最新版本的 Yii，并看看这个问题是否仍然存在。</p>
<h2 id="git-工作流程" tabindex="-1"><a class="header-anchor" href="#git-工作流程"><span>Git 工作流程</span></a></h2>
<p>您想为Yii做贡献吗？太好了！但是，为了增加您的更改被快速接受的可能性，请遵循以下步骤。如果您是第一次接触 Git 和 GitHub ，您可能想先看看 <a href="http://help.github.com/cn" target="_blank" rel="noopener noreferrer">GitHub 帮助内容</a>，<a href="https://docs.github.com/cn/get-started" target="_blank" rel="noopener noreferrer">尝试 Git</a> 或者学习一些关于 <a href="http://nfarina.com/post/9868516270/git-is-simpler" target="_blank" rel="noopener noreferrer">Git 内部数据模型</a> 的知识。</p>
<h3 id="准备开发环境" tabindex="-1"><a class="header-anchor" href="#准备开发环境"><span>准备开发环境</span></a></h3>
<p>下面的步骤将为 Yi i创建一个开发环境，您可以使用它来处理 Yii 框架的核心代码。这些步骤只需要在你第一次贡献的时候完成。</p>
<ol>
<li>在 GitHub 上 <a href="https://docs.github.com/cn/get-started/quickstart/fork-a-repo" target="_blank" rel="noopener noreferrer">Fork</a> Yii 代码库，并将你的 Fork 克隆到你的开发环境中</li>
</ol>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">git</span> clone git@github.com:YOUR-GITHUB-USERNAME/yii2.git</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>如果你在 Linux 中使用 GitHub 设置 Git 有困难，或者出现 “Permission Denied (publickey)” 这样的错误，那么你必须 <a href="https://docs.github.com/cn/get-started/quickstart/set-up-git" target="_blank" rel="noopener noreferrer">设置你的 Git 安装来使用 GitHub</a></p>
<blockquote>
<p>温馨提示：如果你对 Git 不太熟悉，我们推荐你阅读一本很棒的免费的 <a href="https://git-scm.com/book/zh/v2" target="_blank" rel="noopener noreferrer">Pro Git book</a>。</p>
</blockquote>
<ol start="2">
<li>将 Yii 主仓库添加为一个额外的远程 git，称为 “upstream”。</li>
</ol>
<p>切换到你克隆 Yii 的目录，通常是 “yii2”。然后输入以下命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">git</span> remote <span class="token function">add</span> upstream git://github.com/yiisoft/yii2.git</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><ol start="3">
<li>准备测试环境</li>
</ol>
<p>如果您只想处理翻译或文档，则不需要执行以下步骤。</p>
<ul>
<li>运行 <code v-pre>composer install</code> 来安装依赖项（假设您已经完成 <a href="https://getcomposer.org/doc/00-intro.md#globally" target="_blank" rel="noopener noreferrer">composer 全局安装</a>）。</li>
</ul>
<p>如果你打算使用 JavaScript ：</p>
<ul>
<li>运行 <code v-pre>npm install</code> 来安装 JavaScript 测试工具和依赖关系（假设您已经完成 <a href="https://nodejs.org/zh-cn/download/package-manager/" target="_blank" rel="noopener noreferrer">Node.js and NPM 安装</a>）。</li>
</ul>
<blockquote>
<p>Note: JavaScript tests depend on <a href="https://github.com/tmpvar/jsdom" target="_blank" rel="noopener noreferrer">jsdom</a> library which requires Node.js 4 or newer.<br>
Using of Node.js 6 or 7 is more preferable.</p>
</blockquote>
<ul>
<li>
<p>run <code v-pre>php build/build dev/app basic &lt;fork&gt;</code> to clone the basic app and install composer dependencies for the basic app.<br>
<code v-pre>&lt;fork&gt;</code> is URL of your repository fork such as <code v-pre>[](mailto:git@github.com)[git@github.com](mailto:git@github.com):my_nickname/yii2-app-basic.git</code>. If you are core framework contributor you may skip specifying fork.<br>
This command will install foreign composer packages as normal but will link the yii2 repo to<br>
the currently checked out repo, so you have one instance of all the code installed.</p>
<p>Do the same for the advanced app if needed: <code v-pre>php build/build dev/app advanced &lt;fork&gt;</code>.</p>
<p>This command will also be used to update dependencies, it runs <code v-pre>composer update</code> internally.</p>
</li>
</ul>
<blockquote>
<p>Note: The default git repository Urls clone from github via SSH, you may add the <code v-pre>--useHttp</code> flag to the <code v-pre>build</code> command<br>
to use HTTPs instead.</p>
</blockquote>
<p><strong>现在，您已经拥有了修改 Yii 2 的工作背景</strong></p>
<p>以下步骤是可选的。</p>
<ol start="4">
<li>单元测试</li>
</ol>
<p>You can execute unit tests by running <code v-pre>phpunit</code> in the repo root directory. If you do not have phpunit installed globally<br>
you can run <code v-pre>php vendor/bin/phpunit</code> or <code v-pre>vendor/bin/phpunit.bat</code> in case of execution from the Windows OS.</p>
<p>Some tests require additional databases to be set up and configured. You can create <code v-pre>tests/data/config.local.php</code> to override<br>
settings that are configured in <code v-pre>tests/data/config.php</code>.</p>
<p>You may limit the tests to a group of tests you are working on e.g. to run only tests for the validators and redis<br>
<code v-pre>phpunit --group=validators,redis</code>. You get the list of available groups by running <code v-pre>phpunit --list-groups</code>.</p>
<p>You can execute JavaScript unit tests by running <code v-pre>npm test</code> in the repo root directory.</p>
<ol start="5">
<li>Extensions</li>
</ol>
<p>To work on extensions you have to clone the extension repository. We have created a command that can do this for you:</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">php build/build dev/ext <span class="token operator">&lt;</span>extension-name<span class="token operator">></span> <span class="token operator">&lt;</span>fork<span class="token operator">></span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>where <code v-pre>&lt;extension-name&gt;</code> is the name of the extension, e.g. <code v-pre>redis</code> and <code v-pre>&lt;fork&gt;</code> is URL of your extension fork such as <code v-pre>[git@github.com](mailto:git@github.com):my_nickname/yii2-redis.git</code>. If you are core framework contributor you may skip specifying fork.</p>
<p>If you want to test the extension in one of the application templates, just add it to the <code v-pre>composer.json</code> of the application as you would<br>
normally do e.g. add <code v-pre>&quot;yiisoft/yii2-redis&quot;: &quot;~2.0.0&quot;</code> to the <code v-pre>require</code> section of the basic app.<br>
Running <code v-pre>php build/build dev/app basic &lt;fork&gt;</code> will install the extension and its dependencies and create<br>
a symlink to <code v-pre>extensions/redis</code> so you are not working in the composer vendor dir but in the yii2 repository directly.</p>
<blockquote>
<p>Note: The default git repository Urls clone from github via SSH, you may add the <code v-pre>--useHttp</code> flag to the <code v-pre>build</code> command<br>
to use HTTPs instead.</p>
</blockquote>
<h3 id="致力于-bugs-和-features" tabindex="-1"><a class="header-anchor" href="#致力于-bugs-和-features"><span>致力于 bugs 和 features</span></a></h3>
<p>Having prepared your develop environment as explained above you can now start working on the feature or bugfix.</p>
<ol>
<li>Make sure there is an issue created for the thing you are working on if it requires significant effort to fix</li>
</ol>
<p>All new features and bug fixes should have an associated issue to provide a single point of reference for discussion<br>
and documentation. Take a few minutes to look through the existing issue list for one that matches the contribution you<br>
intend to make. If you find one already on the issue list, then please leave a comment on that issue indicating you<br>
intend to work on that item. If you do not find an existing issue matching what you intend to work on, please<br>
<a href="https://learnku.com/docs/yii-framework/2.0.x/contributor-guidelines/report-an-issue.md" target="_blank" rel="noopener noreferrer">open a new issue</a> or create a pull request directly if it is straightforward fix. This will allow the team to<br>
review your suggestion, and provide appropriate feedback along the way.</p>
<blockquote>
<p>对于小的变化或文档问题或简单的修复，你不需要创建一个问题，一个pull request在这种情况下就足够了。</p>
</blockquote>
<ol start="2">
<li>从 Yii 主分支 Pull 最新的代码</li>
</ol>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">git</span> pull upstream</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>对于每一个新的贡献，您都应该从这一点开始，以确保您正在处理最新的代码。</p>
<ol start="3">
<li>基于当前的 Yii 主分支为你的特性创建一个新的分支</li>
</ol>
<blockquote>
<p>That’s very important since you will not be able to submit more than one pull request from your account if you’ll use master.</p>
</blockquote>
<p>每个单独的 bug 修复或更改应该放在它自己的分支中。分支名称应该是描述性的，并从与代码相关的问题的编号开始。如果你没有解决任何特定的问题，请跳过编号。<br>
例如：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">git</span> checkout upstream/master</span>
<span class="line"><span class="token function">git</span> checkout <span class="token parameter variable">-b</span> <span class="token number">999</span>-name-of-your-branch-goes-here</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div></div></div><ol start="4">
<li>施展你的魔法，写你的代码</li>
</ol>
<p>确保它能工作 😃</p>
<p>单元测试总是受欢迎的。经过测试和良好覆盖的代码极大地简化了检查贡献的任务。<br>
作为问题描述的失败的单元测试也被接受。</p>
<ol start="5">
<li>更新 CHANGELOG</li>
</ol>
<p>Edit the CHANGELOG file to include your change, you should insert this at the top of the file under the first heading (the version that is currently under development), the line in the change log should look like one of the following:</p>
<div class="language-php line-numbers-mode" data-highlighter="prismjs" data-ext="php" data-title="php"><pre v-pre class="language-php"><code><span class="line">Bug <span class="token comment">#999: a description of the bug fix (Your Name)</span></span>
<span class="line">Enh <span class="token comment">#999: a description of the enhancement (Your Name)</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div></div></div><p><code v-pre>#999</code> is the issue number that the <code v-pre>Bug</code> or <code v-pre>Enh</code> is referring to.<br>
The changelog should be grouped by type (<code v-pre>Bug</code>,<code v-pre>Enh</code>) and ordered by issue number.</p>
<p>For very small fixes, e.g. typos and documentation changes, there is no need to update the CHANGELOG.</p>
<ol start="6">
<li>提交您的更改</li>
</ol>
<p>add the files/changes you want to commit to the <a href="http://git.github.io/git-reference/basic/#add" target="_blank" rel="noopener noreferrer">staging area</a> with</p>
<div class="language-php line-numbers-mode" data-highlighter="prismjs" data-ext="php" data-title="php"><pre v-pre class="language-php"><code><span class="line">git add path<span class="token operator">/</span>to<span class="token operator">/</span>my<span class="token operator">/</span>file<span class="token operator">.</span>php</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>You can use the <code v-pre>-p</code> option to select the changes you want to have in your commit.</p>
<p>Commit your changes with a descriptive commit message. Make sure to mention the ticket number with <code v-pre>#XXX</code> so GitHub will automatically link your commit with the ticket:</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">git</span> commit <span class="token parameter variable">-m</span> <span class="token string">"A brief description of this change which fixes #999 goes here"</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><ol start="7">
<li>从上游拉取最新的 Yii 代码到你的分支中</li>
</ol>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">git</span> pull upstream master</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>This ensures you have the latest code in your branch before you open your pull request. If there are any merge conflicts,<br>
you should fix them now and commit the changes again. This ensures that it’s easy for the Yii team to merge your changes<br>
with one click.</p>
<ol start="8">
<li>当解决任何冲突后，将你的代码推送到 GitHub</li>
</ol>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">git</span> push <span class="token parameter variable">-u</span> origin <span class="token number">999</span>-name-of-your-branch-goes-here</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>The <code v-pre>-u</code> parameter ensures that your branch will now automatically push and pull from the GitHub branch. That means<br>
if you type <code v-pre>git push</code> the next time it will know where to push to. This is useful if you want to later add more commits<br>
to the pull request.</p>
<ol start="9">
<li>针对上游打开一个 <a href="https://help.github.com/articles/creating-a-pull-request-from-a-fork/" target="_blank" rel="noopener noreferrer">拉取请求（pull request）</a>。</li>
</ol>
<p>Go to your repository on GitHub and click “Pull Request”, choose your branch on the right and enter some more details in the comment box. To link the pull request to the issue put anywhere in the pull comment <code v-pre>#999</code> where 999 is the issue number.</p>
<blockquote>
<p>Note that each pull-request should fix a single change. For multiple, unrelated changes, please open multiple pull requests.</p>
</blockquote>
<ol start="10">
<li>有人会检查你的代码</li>
</ol>
<p>Someone will review your code, and you might be asked to make some changes, if so go to step #6 (you don’t need to open another pull request if your current one is still open). If your code is accepted it will be merged into the main branch and become part of the next Yii release. If not, don’t be disheartened, different people need different features and Yii can’t be everything to everyone, your code will still be available on GitHub as a reference for people who need it.</p>
<ol start="11">
<li>清理</li>
</ol>
<p>After your code was either accepted or declined you can delete branches you’ve worked with from your local repository<br>
and <code v-pre>origin</code>.</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">git</span> checkout master</span>
<span class="line"><span class="token function">git</span> branch <span class="token parameter variable">-D</span> <span class="token number">999</span>-name-of-your-branch-goes-here</span>
<span class="line"><span class="token function">git</span> push origin <span class="token parameter variable">--delete</span> <span class="token number">999</span>-name-of-your-branch-goes-here</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><ul>
<li>注意：</li>
</ul>
<p>To detect regressions early every merge to the Yii codebase on GitHub will be picked up by<br>
<a href="http://travis-ci.com/" target="_blank" rel="noopener noreferrer">Travis CI</a> for an automated testrun. As core team doesn’t wish to overtax this service,<br>
<a href="https://docs.travis-ci.com/user/customizing-the-build/#Skipping-a-build" target="_blank" rel="noopener noreferrer"><code v-pre>[ci skip]</code></a> will be included to the merge description if the pull request:</p>
<ul>
<li>affect javascript, css or image files only,</li>
<li>updates the documentation,</li>
<li>modify fixed strings only (e.g. translation updates)</li>
</ul>
<p>Doing so will save travis from commencing testruns on changes that are not covered by tests in the first place.</p>
<ul>
<li>命令行概述 (针对高级贡献者)</li>
</ul>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">git</span> clone git@github.com:YOUR-GITHUB-USERNAME/yii2.git</span>
<span class="line"><span class="token function">git</span> remote <span class="token function">add</span> upstream git://github.com/yiisoft/yii2.git</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div></div></div><div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">git</span> fetch upstream</span>
<span class="line"><span class="token function">git</span> checkout upstream/master</span>
<span class="line"><span class="token function">git</span> checkout <span class="token parameter variable">-b</span> <span class="token number">999</span>-name-of-your-branch-goes-here</span>
<span class="line"></span>
<span class="line">/* <span class="token keyword">do</span> your magic, update changelog <span class="token keyword">if</span> needed */</span>
<span class="line"></span>
<span class="line"><span class="token function">git</span> <span class="token function">add</span> path/to/my/file.php</span>
<span class="line"><span class="token function">git</span> commit <span class="token parameter variable">-m</span> <span class="token string">"这个 fixes #999 的简要描述在这里"</span></span>
<span class="line"><span class="token function">git</span> pull upstream master</span>
<span class="line"><span class="token function">git</span> push <span class="token parameter variable">-u</span> origin <span class="token number">999</span>-name-of-your-branch-goes-here</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><blockquote>
<p>💖喜欢本文档的，欢迎点赞、收藏、留言或转发，谢谢支持！<br>
作者邮箱：zhuzixian520@126.com，github地址：<a href="https://github.com/zhuzixian520" target="_blank" rel="noopener noreferrer">github.com/zhuzixian520</a></p>
</blockquote>
</div></template>


